Cream of the Crop 20

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / program / vsa256.zip / VSA256.TXT < prev next >

Wrap

Text File | 1996-03-20 | 84KB | 2,090 lines

******************************************************************************* Blueberry Graphics(TM) 7910 W. Brookridge Dr., Middletown, MD 21769 http://ourworld.compuserve.com/homepages/blueberry ******************************************************************************* VSA256 Graphics Library For C Programmers Version 4.0 March 17, 1996 Copyright Spyro Gumas, 1992 - 1996. All Rights Reserved Look what You get for Registering!! - Royalty Free Use of VSA256 in Your Programs! - Graphics Mouse Library! - Joystick Library & Source Code! - Image Processing Library & Source Code! - 32 Bit WATCOM C Compiler compatible library! - 3D Graphics Library! - On line support through CompuServe! - Printed Users Manual and Software Disk! - Half Price upgrade to next version! (See Page 7 for Details) Page: 1 1.0 Introduction 4 1.1 Revision History 5 1.2 Benefits of Registering 7 1.3 Distribution Files 8 2.0 The Programming Environment 9 2.1 Setting Up The VESA Environment 9 2.2 Global Graphics Parameters 9 2.3 Compiler Compatibility 10 3.0 Function Descriptions 12 3.1 VESA Configuration Functions 12 3.1.1 vsa_set_svga_mode 12 3.1.2 vsa_get_svga_mode 13 3.1.3 vsa_init 13 3.2 Miscellaneous Functions 14 3.2.1 vsa_set_display_start 14 3.2.2 vsa_get_display_start 14 3.2.3 vsa_set_draw_page 14 3.2.4 vsa_get_draw_page 15 3.2.5 vsa_set_view_page 15 3.2.6 vsa_get_view_page 15 3.2.7 vsa_wait_vsync 16 3.3 Attribute Functions 16 3.3.1 vsa_set_color 16 3.3.2 vsa_get_color 16 3.3.3 vsa_set_text_color 17 3.3.4 vsa_get_text_color 17 3.3.5 vsa_set_clip_mode 17 3.3.6 vsa_get_clip_mode 17 3.3.7 vsa_set_triangle_clip_mode 17 3.3.8 vsa_get_triangle_clip_mode 18 3.3.9 vsa_set_viewport 18 3.3.10 vsa_get_viewport 18 3.4 Color Look Up Table Functions 19 3.4.1 vsa_read_color_register 19 3.4.2 vsa_write_color_register 19 3.4.3 vsa_read_color_block 19 3.4.4 vsa_write_color_block 20 3.5 Text Functions (Vector Stroked!) 20 3.5.1 vsa_set_text_cursor 21 3.5.2 vsa_get_text_cursor 21 3.5.3 vsa_set_text_scale 21 3.5.4 vsa_get_text_scale 22 3.5.5 vsa_set_text_cursor_mode 22 3.5.6 vsa_get_text_cursor_mode 22 3.5.7 vsa_write_string 22 3.5.8 vsa_write_string_alt 23 3.6 Basic Drawing Functions 23 3.6.1 vsa_move_to 23 3.6.2 vsa_set_pixel 23 3.6.3 vsa_get_pixel 24 3.6.4 vsa_line_to 24 3.6.5 vsa_gouraud_line 24 3.6.6 vsa_rect 25 Page: 2 3.6.7 vsa_rect_fill 25 3.6.8 vsa_triangle 25 3.6.9 vsa_triangle_fill 25 3.6.10 vsa_shaded_triangle 26 3.6.11 vsa_h_line 26 3.6.12 vsa_v_line 26 3.7 Specialized Drawing Functions 27 3.7.1 vsa_raster_line 27 3.7.2 vsa_get_raster_line 27 3.7.3 vsa_image_size 27 3.7.4 vsa_get_image 28 3.7.5 vsa_put_image 28 4.0 Nitty Gritties 29 4.1 Registration Information 29 4.2 Software License 30 4.3 Disclaimer 31 4.4 Technical Support 31 5.0 Application Notes 32 5.1 Using Triangles 32 5.2 Page Flipping 32 5.3 Using Off Screen Video Memory 32 5.4 Expanding the VSA_FONT Character Set 33 6.0 Graphics Library Extensions 33 6.1 The VSA256 GLE Developers Program 33 6.2 Existing Graphics Library Extensions 35 7.0 Appendix 36 7.1 VSA.H Include File 36 7.2 VSA_FONT.H Include File 38 Page: 3 1.0 INTRODUCTION The VSA256 Graphics Library provides a C programmer with the tools necessary to generate graphics output on a video adapter running with the Video Electronics Standards Association (VESA) version 1.2 BIOS extensions. The VESA BIOS extensions standardize the Super VGA (SVGA) graphics environment. The name "VSA256" reflects the fact that this library is aimed at supporting the 256 color video modes 100h, 101h, 103h, 105h, and 107h defined within the VESA standard (See table in section 3.1.1). Page: 4 1.1 Revision History Version 1.0 is the original SHAREWARE version of the VSA256 Graphics Library. Version 1.1 is the SHAREWARE version of the VSA256 Graphics Library which corrected some compiler compatibility problems and added the vsa_get_raster_line function which was necessary for the TIFF256 Graphics Library Extensions. Some drawing errors were also corrected. Version 2.0b is the REGISTERED version of the VSA256 Graphics Library. Whereas the VSA256 Graphics Library Version 1.x is shareware, Version 2.0b IS NOT shareware and may only be used in accordance with the terms of the purchase agreement. Version 3.2 is presented to the general public in the true spirit of shareware. I no longer maintain a separate registered version of this library. Version 3.2 of the VSA256 Graphics Library is presented as ShareWare with high hopes that the programmers who use this library will feel good about sending in the registration. - Added Viewport Clipping - Now works with Small, Medium, - Added BitBLT functions. Compact Large memory models with - Added Vector Text: Infinitely Borland (Already did so with scaleable and set to nearest Microsoft) pixel, fonts are fully user - Fixed "unresolved external definable! _fstrlen" linker error (Turbo C) - Added Global Parameter - Now text routines work with ALL VSA_ATI_COLOR for some ATI video adapters cards. (defaults to 0, set - Made all functions in VSA.H See it to 1 if ATI card locks up. external, no more "Multiple README.TXT) Declaration" warnings Version 4.0 provides significantly increased drawing speeds over version 3.2 (see the VSA256 Revision Comparison Table). In addition, real functionality improvements are introduced into the library as a result of user feedback. - MAJOR SPEED-UP of all drawing - Added page flipping support for functions! double buffered drawing - Changed vsa_set_viewport so - Made the user definable FONT array that 'BOTTOM' can be set expandable, to support foreign beyond bottom of displayable languages video memory. Now the user - Added vsa_get... functions for all can use off screen memory to existing vsa_set... functions store bitmaps for BitBLTs - Made VSA_ATI_COLOR autodetect ATI cards Page: 5 VSA256 Revision Comparison Table Drawing Functions* V1 V2 V3 V4 Control Functions V1 V2 V3 V4 ------------------------------------ ------------------------------------- vsa_move_to * * * * vsa_set_svga_mode * * * * vsa_set_pixel * * * * vsa_get_svga_mode * * * * vsa_get_pixel * * vsa_init * * * * vsa_line_to * 3x 3x 6x vsa_set_display_start * * * * vsa_gouraud_line * * 2x vsa_get_display_start * * * * vsa_rect * 3x 3x 6x vsa_set_draw_page * vsa_rect_fill * * * 4x vsa_get_draw_page * vsa_triangle * vsa_set_view_page * vsa_triangle_fill * * 2x vsa_get_view_page * vsa_shaded_triangle * * 2x vsa_wait_vsync * * vsa_h_line * 3x 3x 4x vsa_set_color * * * * vsa_v_line * * * 2x vsa_get_color * vsa_raster_line * 2x 2x 3x vsa_set_text_color * * * * vsa_get_raster_line * * 3x vsa_get_text_color * vsa_image_size * * vsa_set_clip_mode * * vsa_get_image * 3x vsa_get_clip_mode * vsa_put_image * 3x vsa_set_triangle_clip_mode * vsa_get_triangle_clip_mode * vsa_set_viewport * * vsa_get_viewport * Text Functions V1 V2 V3 V4 ------------------------------------- vsa_set_text_cursor * * * * vsa_get_text_cursor * * vsa_set_text_scale * * Color Functions V1 V2 V3 V4 vsa_get_text_scale * ------------------------------------- vsa_set_text_cursor_mode * * * * vsa_read_color_register * * * * vsa_get_text_cursor_mode * vsa_write_color_register * * * * vsa_write_string * * * * vsa_read_color_block * * * * vsa_write_string_alt * * * * vsa_write_color_block * * * * * For Drawing Functions, speed-up factors shown are relative to speed of VSA256 Version 1.0 Page: 6 1.2 Benefits of Registering If you use this program beyond an initial evaluation period, you must register your use with a $34 remittance to the author .. me. In addition to the good feeling that you get for sustaining a late night hacking obsession, you get the following benefits for registering: 1) Royalty Free Use of VSA256 in Your Programs! Feel free to distribute your programs for profit with no royalty fees. See section 4.2. 2) Graphics Mouse Library! Use this library to integrate Mouse input with your graphics applications. Get precise updates of mouse position, update screen cursor, read mouse buttons, and more. Invent your own graphical user interface, give your apps that professional feel, have tons of fun! 3) Joystick Library with Source Code! Integrate Joystick input with your graphics applications. Write a flight simulator, boat driver, or your own unique use of this agile input device. 4) IMP256 Image Processing Library and Source Code! With this library you can learn all about image sharpening, embossing, blurring, color balancing, and enhancement. 5) 32 Bit WATCOM C Compiler compatible VSA256 and TIFF256 libraries! Get the edge on performance. 6) 3D Graphics Library! Don't live in a flat world. Add the missing 3rd dimension to your creations. This library lets you create 3d objects, set your view point, and perform 3d transformations including scale, offset, and rotation. Supports wireframe, solid, and Gouraud shaded objects. (Still being developed). 7) On line support through CompuServe. 8) Printed Users Manual and Current Version Software on Disk. 9) One Half Price Upgrade to the next version, as it becomes available. AND As if that's not enough, for a measly $15 more, you will get: 10) TIFF256 Graphics Library Extensions. This extension to the VSA256 library lets you read TIFF formatted graphic image files, display them, modify them, and write them back to disk. Furthermore, anything that you create and display on the screen can be saved as a TIFF image file. Page: 7 AND 11) The following public domain full color TIFF image files to get you started: VENUS.TIF EARTH.TIF MOON.TIF MARS.TIF SATURN.TIF NEPTUNE.TIF SHUTTLE.TIF ASTRONTS.TIF WEATHER.TIF MANDRILL.TIF (What, no Ginsu Knife Set?) 1.3 Distribution Files The distribution of the VSA256 Graphics Library Version 4.0 consists of the 12 files listed below plus the drivers listed in Section 2.1. These files are archived in the file VSA256.ZIP. To extract, just type 'PKUNZIP VSA256' in the directory that you want the files extracted to. VSA256MS.LIB VSA256 Graphics Library (Microsoft C compatible). VSA256BC.LIB VSA256 Graphics Library(Borland C Compatible). VSA.H VSA256 Include file required in your program. VSA_FONT.H VSA256 Include file required in your program. VSA_DEMO.C VSA256 Demonstration program (Source Code). VSA_DEMO.EXE VSA256 Demonstration program (Executable). VSA_DEMO.MAK VSA_DEMO Make file for Microsoft C. VSA_DEMO.PRJ VSA_DEMO Project file for Borland C/C++ V3.1. VSA_DEMO.IDE VSA_DEMO Project file for Borland C/C++ V4.0. VSA256.TXT This text document. ORDER.TXT Text file order form for registration and upgrades. README.TXT Text file with important info. Page: 8 2.0 THE PROGRAMMING ENVIRONMENT 2.1 Setting Up The VESA Environment The VSA256 Graphics Library works with any (any?) IBM PC, XT, AT or compatible computer equipped with a VESA compatible SVGA video adapter card capable of 256 colors. Most of the video cards sold today are VESA compatible with the VESA BIOS built in to the card. A math coprocessor chip is not required. For older SVGA video cards which are not VESA compatible, the VESA BIOS Extensions must be loaded as a Terminate and Stay Resident (TSR) program before using the VSA256 Graphics Library. This is accomplished by executing the appropriate driver or adding it to your AUTOEXEC.BAT file. If your video adapter card came with a VESA driver, use it. Otherwise use one of the drivers provided depending on the video adapter card installed in the PC as follows: APPIAN \APPIAN\APVESA.EXE ATI \ATI\VESA.COM C&T \C&T\VESA451.COM (or VESA452.COM) CIRRUS \CIRRUS\CRUSVESA.COM EVEREX \EVEREX\EVRXVESA.COM GENOA \GENOA\VESA.COM OAK \OAK\37VESA.COM (or67VESA.COM) ORCHID \ORCHID\ORCHDVSA.COM PARADISE \PARADISE\VESA.EXE SIGMA \SIGMA\SIGVESA.COM STB \STB\STB-VESA.COM TECMAR \TECMAR\VGAVESA.COM TRIDENT \TRIDENT\VESA.EXE VIDEO7 \VIDEO7\V7VESA.COM 2.2 Global Graphics Parameters The VSA.H and VSA_FONT.H files are used as include files during program development. These files includes all of the function prototypes and define the global graphics parameters that describe the specific video adapter installed in the PC (see Section 7). The global graphics parameters are initialized by the vsa_init function and are described below: XResolution: Unsigned, number of screen pixels across (x dimension). YResolution: Unsigned, number of screen pixels high (y dimension). XCharResolution: Unsigned, number of screen characters across (x dimension). YCharResolution: Unsigned, number of screen characters high (y dimension). XCharSize: Unsigned char, the character drawn cell width. YCharSize: Unsigned char, the character drawn cell height. BitsPerPixel: Unsigned char, the number of bits per pixel. XLeft: Int, the left edge of the screen clipping Viewport. Page: 9 YTop: Int, the top edge of the screen clipping Viewport. XRight: Int, the right edge of the screen clipping Viewport. YBottom: Int, the bottom edge of the screen clipping Viewport. Text_X_Scale: Float, multiplies XCharBase to get text width in pixels. Text_Y_Scale: Float, multiplies YCharBase to get text height in pixels. XCharBase: Unsigned, the fundamental text character width. YCharBase: Unsigned, the fundamental text character height. ASC[96][72]: Unsigned Char, the 2D array of character vertices. VSA_ATI_COLOR Int, set it to 1 if your ATI board locks up. Defaults to 0. Note that there is a fundamental difference between how you use VSA.H and how you use VSA_FONT.H. The function prototypes and the global parameter declarations are all "extern" in VSA.H. This means that you can plop VSA.H into the top of each and every code module (file) which is part of your project. VSA_FONT.H, on the other hand, declares and initializes the 'ASC[][]' array. Since I want you, the programmer, to have access to the font definitions, I couldn't make these parameter declarations "extern". What this means for you is that if you have multiple code modules (files), only include VSA_FONT.H in one of the files. Then put the following two lines of code at the top of each and every other code module (file) in your project: extern unsigned far XCharBase, far YCharBase; extern unsigned char far ASC[][72]; 2.3 Compiler Compatibility The VSA256MS.LIB was compiled using Microsoft's Quick C 2.5 and it seems to also work well with Microsoft C 6.0 and 7.0. I have received reports of compatibility problems with Microsoft C 5.0. The VSA256BC.LIB was compiled using Borland's C/C++ 3.1 and it seems to also work well with Borland C/C++ 3.0 and 4.0. I have received conflicting reports of compatibility problems with Borland's Turbo C 2.0 and 3.0. I appreciate any feedback that programmers send me along these lines so that I can continue to improve this product. Important Note for Borland Users: You MUST set the -Fs compiler option. This tells the compiler to assume that the Stack Segment equals the Data Segment. In the Programmers IDE, you go to Options / Compiler / Code Generation and select "Always" under the option "Assume SS Equals DS". Why? The VSA256 library can be used in Tiny, Small, Medium, Compact, and Large memory models in both the Microsoft and Borland environments. Microsoft always puts the Stack Segment in the first Data Segment, but Borland sets up a separate Stack Segment (for Compact and Large memory models) unless you specify the -Fs option. Failing to set -Fs will result in a "Stack Overflow!" error when running code compiled in Compact or Large memory models. Page: 10 Important Note for C++ Developers: I compiled and linked the VSA256 Graphics Library as a C library (not C++). I know that Borland will give you grief if you try to link in my C library with your C++ program. You need to do one of two things: 1) Write your program as a C program (.C extension, not .CPP) or 2) Contact me and I can send you a C++ compiled version of the library. Page: 11 3.0 FUNCTION DESCRIPTIONS This section describes the functions supported in the VSA256 Graphics Library. To use these functions, link your program with the appropriate library listed below depending on the compiler being used. Borland C, C++ or Turbo C - VSA256BC.LIB Microsoft C or Quick C - VSA256MS.LIB In the following sections each function is listed along with a definition of its inputs and return values. A description is provided followed by the version in which the function became available. Finally, if applicable, comments are provided. 3.1 VESA Configuration Functions 3.1.1 vsa_set_svga_mode Prototype: unsigned vsa_set_svga_mode(unsigned video_mode); Description: This routine sets the video mode. The mode number may be any of the standard VESA SVGA mode numbers as defined in the tables below. The mode is passed to this routine through the 'video_mode' parameter. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). It should be noted that this routine will also work with standard MDA, CGA, EGA, and VGA mode numbers, however the rest of the VSA256 functions will not necessarily work. Availability: In VSA256 Graphics Library Version 1.0 and up. WARNING: Use vsa_init Instead (Section 3.1.3)! If you don't use vsa_init, then the rest of the routines won't work because they depend on the global parameters initialized by vsa_init; VESA SVGA VIDEO MODES GRAPHICS Mode Resolution Colors 100h 640x400 256 101h 640x480 256 102h 800x600 16 103h 800x600 256 104h 1024x768 16 105h 1024x768 256 106h 1280x1024 16 107h 1280x1024 256 Page: 12 TEXT Mode Columns Rows 108h 80 60 109h 132 25 10Ah 132 43 10Bh 132 50 10Ch 132 60 3.1.2 vsa_get_svga_mode Prototype: unsigned vsa_get_svga_mode(unsigned far *video_mode); Description: This routine gets the current video mode. The mode is returned to the calling routine via the 'video_mode' pointer. The mode number may be any of the standard VESA SVGA mode numbers as defined in Section 3.1.1. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). Availability: In VSA256 Graphics Library Version 1.0 and up. Comments: Works in all VESA video modes. Also works in MDA, CGA, EGA and VGA Modes. 3.1.3 vsa_init Prototype: unsigned vsa_init(unsigned video_mode); Description: This routine sets the video mode and initializes the VESA graphics environment. This routine must be called prior to the use of any of the routines in Sections 3.2 through 3.7. The mode number may be any of the standard VESA SVGA mode numbers as defined in Section 3.1.1. If the mode number is not a VESA SVGA mode number, this routine will still set the desired video mode, however, the VESA graphics environment will not be initialized and subsequent calls to drawing routines will produce unpredictable results. The mode is passed to this routine through the 'video_mode' parameter. This routine returns a 'fail_flag' = 0 if the call was a success. For failures, the 'fail_flag' has the following meaning: 1 - Can not get Super VGA Environment information. Make sure VESA BIOS TSR is loaded. 2 - VESA BIOS TSR not loaded. Need to load one. 3 - Specified Video Mode not supported by this video card. Try another mode. 4 - Specified Video Mode was set but it is not one of the VESA standard modes. VSA256 may not function properly. Page: 13 5 - Can not get Super VGA Video Mode Data. Make sure correct VESA BIOS TSR is loaded. Availability: In VSA256 Graphics Library Version 1.0 and up. Comments: Starting with Version 3.0, VSA256 no longer prints out error messages automatically to the screen. The programmer gets full status feed back via the 'fail_flag' and can do as he/she sees fit. Also note that VSA256 no longer cares if the specific VESA BIOS Extensions TSR being used supports text functions. This is due to the new implementation of text using vector strokes (see vsa_write_string). 3.2 Miscellaneous Functions 3.2.1 vsa_set_display_start Prototype: unsigned vsa_set_display_start(unsigned x_strt, unsigned y_strt); Description: This routine sets the current start pixel address which is mapped to the upper left corner of the display. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). Availability: In VSA256 Graphics Library Version 1.0 and up. Comments: Don't bother with this unless you are hard core. Use vsa_set_draw_page and vsa_set_view_page instead! 3.2.2 vsa_get_display_start Prototype: unsigned vsa_get_display_start(unsigned far *x_strt, unsigned far *y_strt); Description: This routine gets the current start pixel address which is mapped to the upper left corner of the display. This routine returns a 'fail_flag' = 0 if the call was a success (a 1 for failure). Availability: In VSA256 Graphics Library Version 1.0 and up. Comments: See vsa_get_draw_page and vsa_get_view_page also! 3.2.3 vsa_set_draw_page Prototype: void vsa_set_draw_page(int page); Description: This routine sets the current DRAW_PAGE in video memory to 'page'. All drawing actions occur into the current DRAW_PAGE of Page: 14 memory. This routine is useful when you want to display from one portion of video memory (see vsa_set_view_page) while drawing into another. To determine the total available number of pages in video memory, divide the total available video RAM size by the display area. For example a 1MB SVGA card running in 640 x 480 mode has 3.4 pages (you can reasonably use pages 0, 1, and 2 for a total of 3 pages). Setting 'page' to a value beyond the number of existing pages will cause unpredictable stuff. After vsa_init, the DRAW_PAGE defaults to 0. Availability: In VSA256 Graphics Library Version 4.0 and up. Comments: Page flipping (Ping Pong Buffering or Double Buffering) is a really cool thing to do because it makes your redraws look instantaneous (see Sec. 5.2). 3.2.4 vsa_get_draw_page Prototype: int vsa_get_draw_page(void); Description: This routine returns the current DRAW_PAGE. Availability: In VSA256 Graphics Library Version 4.0 and up. 3.2.5 vsa_set_view_page(int page); Prototype: void vsa_set_view_page(int page); Description: This routine sets the current VIEW_PAGE in video memory to 'page'. The current screen display comes from the VIEW_PAGE of memory. This routine is useful when you want to display from one portion of video memory while drawing into another (see vsa_set_draw_page). To determine the total available number of pages in video memory, divide the total available video RAM size by the display area. For example a 1MB SVGA card running in 640 x 480 mode has 3.4 pages (you can reasonably use pages 0, 1, and 2 for a total of 3 pages). Setting 'page' to a value beyond the number of existing pages will cause unpredictable stuff. After vsa_init, the VIEW_PAGE defaults to 0. Availability: In VSA256 Graphics Library Version 4.0 and up. Comments: Page flipping (Ping Pong Buffering or Double Buffering) is a really cool thing to do because it makes your redraws look instantaneous (see Sec. 5.2). Page: 15 3.2.6 vsa_get_view_page Prototype: int vsa_get_view_page(void); Description: This routine returns the current VIEW_PAGE. Availability: In VSA256 Graphics Library Version 4.0 and up. 3.2.7 vsa_wait_vsync Prototype: void vsa_wait_vsync(void ); Description: This routine waits until the beginning of the CRTs' vertical retrace period before returning control to the calling program. If vsa_wait_vsync is called while the CRT is in vertical retrace, this routine waits until the completion of the current retrace period and the completion of the following active scan and then returns at the beginning of the next vertical retrace period. The programmer can use this function to precede drawing functions which must be executed during CRT Vertical Retrace. The programmer is assured the full retrace time for his use. Availability: In VSA256 Graphics Library Version 3.0 and up. Comments: Try using vsa_wait_vsync just prior to each vsa_set_view_page call to get rid of flicker effects (see Sec. 5.2). 3.3 Attribute Functions 3.3.1 vsa_set_color Prototype: void vsa_set_color(unsigned color); Description: This routine sets the current drawing color which is used in drawing pixels, lines, rectangles, and triangles. The "color" is an 8 bit value from 0 to 255 which is used to index in to the Color Look Up Table (see Section 3.4). Availability: In VSA256 Graphics Library Version 1.0 and up. 3.3.2 vsa_get_color Prototype: unsigned vsa_get_color(void); Description: This routine returns the current drawing color. Availability: In VSA256 Graphics Library Version 4.0 and up. Page: 16 3.3.3 vsa_set_text_color Prototype: void vsa_set_text_color(unsigned color); Description: This routine sets the current text color which is used in drawing text. The "color" is an 8 bit value from 0 to 255 which is used to index in to the Color Look Up Table (see Section 3.4). Since the text is drawn using vector strokes, the background is unaffected by newly drawn text. Note: this also means that drawing a text 'space' character does nothing but index the text pointer. Availability: In VSA256 Graphics Library Version 1.0 and up. 3.3.4 vsa_get_text_color Prototype: unsigned vsa_get_text_color(void); Description: This routine returns the current text color. Availability: In VSA256 Graphics Library Version 4.0 and up. 3.3.5 vsa_set_clip_mode Prototype: void vsa_set_clip_mode(unsigned mode); Description: This routine sets the Viewport clipping mode ON if 'mode' = 1, OFF otherwise. After vsa_init, the default is ON. Availability: In VSA256 Graphics Library Version 3.0 and up. 3.3.6 vsa_get_clip_mode Prototype: unsigned vsa_get_clip_mode(void); Description: This routine returns the Viewport clipping mode. Availability: In VSA256 Graphics Library Version 4.0 and up. 3.3.7 vsa_set_triangle_clip_mode Prototype: void vsa_set_triangle_clip_mode(unsigned mode); Description: This routine sets the Triangle clipping mode ON if 'mode' = 1, OFF otherwise. After vsa_init, the default is ON. This function only affects clipping for triangles drawn with vsa_triangle, Page: 17 vsa_triangle_fill, and vsa_shaded_triangle. For triangle clipping to be on, both Viewport clipping mode AND Triangle clipping mode must be on. Availability: In VSA256 Graphics Library Version 4.0 and up. Comments: See Section 5.1 for a short discussion about this. 3.3.8 vsa_get_triangle_clip_mode Prototype: unsigned vsa_get_triangle_clip_mode(void); Description: This routine returns the Triangle clipping mode. Availability: In VSA256 Graphics Library Version 4.0 and up. 3.3.9 vsa_set_viewport Prototype: void vsa_set_viewport(int left,int top,int right,int bottom); Description: This routine sets the global Viewport clipping parameters XLeft, YTop, XRight, and YBottom. Note that vsa_init initializes these values to the full screen dimensions for the selected video mode. Viewport clipping is turned on and off through the vsa_set_clip_mode function. By default, clip mode is ON after vsa_init. When clip mode is ON, all items drawn on the screen through VSA256 functions are clipped to the screen Viewport rectangle defined by XLeft, YTop, XRight, and YBottom. NOTE: Triangles will only be clipped if BOTH Viewport clipping AND Triangle clipping are on (see vsa_set_triangle_clip_mode). Availability: In VSA256 Graphics Library Version 3.0 and up. Comments: If you have enough video RAM, you can set 'BOTTOM' past the bottom of the screen. Then you can draw things down there (like buttons) and BitBLT them up to the displayed area as needed (see Sec. 5.3). 3.3.10 vsa_get_viewport Prototype: void vsa_get_viewport(int far *pleft,int far *ptop, int far *pright,int far *pbottom); Description: This routine returns the global Viewport clipping parameters XLeft, YTop, XRight, and YBottom via the pointers '*pleft', '*ptop', '*pright', and '*pbottom' respectively. Availability: In VSA256 Graphics Library Version 4.0 and up. Page: 18 3.4 Color Look Up Table Functions The Color Look Up Table consists of 256 registers and each register stores an 18 bit value defining 6 bit levels for each of red, green, and blue. The drawing functions index into the Color Look Up Table with an 8 bit value (usually set with vsa_set_color) to determine the drawing color. With the following functions, the Color Look Up Table can be read or modified one register at a time or all at once in a block operation. 3.4.1 vsa_read_color_register Prototype: void vsa_read_color_register(unsigned index,unsigned char far *redptr,unsigned char far *grnptr,unsigned char far *bluptr); Description: This routine reads the value of one of the 256 color registers as defined by 'index'. Pointers to the red, green, and blue components of the color are returned (6 bits each for red, green, and blue). Availability: In VSA256 Graphics Library Version 1.0 and up. 3.4.2 vsa_write_color_register Prototype: void vsa_write_color_register(unsigned index,unsigned char red, unsigned char green,unsigned char blue); Description: This routine writes the value of one of the 256 color registers as defined by 'index'. The calling routine provides 'red', 'green', and 'blue' components of the color (6 bits each for red, green, and blue). Availability: In VSA256 Graphics Library Version 1.0 and up. 3.4.3 vsa_read_color_block Prototype: void vsa_read_color_block(unsigned start,unsigned count, unsigned char far *array); Description: This routine reads 'count' (Range: 1 to 256) consecutive color registers starting at 'start' (Range: 0 to 255) within the Color Look Up Table. The 'count' must be less than or equal to 256 - 'start'. The values read from the color registers are returned from this routine in 'array[]'. Each element of 'array[]' is a byte, and the size of 'array[]' is equal to three times 'count'. Every three bytes in 'array[]' represents the red, green, and blue color values Page: 19 respectively for one color register. Each color component (red, green, or blue) is a byte value but only ranges from 0 to 63. Availability: In VSA256 Graphics Library Version 1.0 and up. 3.4.4 vsa_write_color_block Prototype: void vsa_write_color_block(unsigned start,unsigned count, unsigned char far *array); Description: This routine writes 'count' (Range: 1 to 256) consecutive color registers starting at 'start' (Range: 0 to 255) within the Color Look Up Table. The 'count' must be less than or equal to 256 - 'start'. The values loaded into the color registers are passed to this routine in 'array[]'. Each element of 'array[]' is a byte, and the size of 'array[]' is equal to three times 'count'. Every three bytes in 'array[]' represents the red, green, and blue color values respectively for one color register. Each color component (red, green, or blue) is a byte value but only ranges from 0 to 63. Availability: In VSA256 Graphics Library Version 1.0 and up. 3.5 Text Functions (Vector Stroked!) Starting with VSA256 Version 3.0, text support has been completely REVAMPED! The library no longer relies on the video card manufacturers BIOS to get text support. Instead each character is drawn using 2D vector strokes. The advantages are as follows: - Text now works with ALL video cards! - Now text is Infinitely scaleable. - Text positioning resolution is down to 1 pixel. - Background color is preserved. - The programmer can define his own fonts in VSA_FONT.H (see Sec. 5.4) Some minor incompatibilities with VSA256 version 2.0 were introduced due to the changes and they are as follows: - vsa_write_string now takes x,y (in pixel coordinates) instead of row,col (in character coordinates) as the first two parameters. - The vsa_write_char function was deleted. - The supported ASCII characters are the printable characters from ASCII code 32 to ASCII code 127. Page: 20 Your existing code should take very little editing to make these changes, especially if you write a macro to edit all occurrences of vsa_write_string as follows: OLD - vsa_write_string(row,col,color,text); NEW - vsa_write_string(col*XCharSize,row*YCharSize,color,text); 3.5.1 vsa_set_text_cursor Prototype: void vsa_set_text_cursor(int x,int y); Description: This routine sets the current text cursor position to 'x,y' in pixel coordinates. The current text cursor position is only used by vsa_write_string_alt. Availability: In VSA256 Graphics Library Version 1.0 and up. Comments: Note that with Rev 3.0 this function changed to pixel coordinates to support vector stroked fonts. 3.5.2 vsa_get_text_cursor Prototype: void vsa_get_text_cursor(int far *px,int far *py); Description: This routine gets the current text cursor position and returns the x and y positions via the pointers '*px' and '*py' respectively. The returned positions are in pixel coordinates. The current text cursor position is only used by vsa_write_string_alt. Availability: In VSA256 Graphics Library Version 3.0 and up. 3.5.3 vsa_set_text_scale Prototype: void vsa_set_text_scale(float x_scale,float y_scale); Description: This routine sets the x and y scale factors for text drawn with the vsa_write_string and vsa_write_string_alt routines. The 'x_scale' and 'y_scale' scale factors are applied to the global parameters XCharBase and YCharBase respectively to determine the drawn text character width and height in pixels. Since these scale factors are floating point, continuously and infinitely scaleable text characters are possible. This routine automatically adjusts the global parameters XCharSize, YCharSize, XCharResolution and YCharResolution to their appropriate values. After vsa_init, the x_scale and y_scale factors both default to 1.0. Availability: In VSA256 Graphics Library Version 3.0 and up. Page: 21 3.5.4 vsa_get_text_scale Prototype: void vsa_get_text_scale(float far *px_scale,float far *py_scale); Description: This routine returns the x and y scale factors used for text via the pointers '*px' and '*py' respectively. Availability: In VSA256 Graphics Library Version 4.0 and up. 3.5.5 vsa_set_text_cursor_mode Prototype: void vsa_set_text_cursor_mode(unsigned mode); Description: This routine determines the mode of the text cursor operation. If 'mode' is '0' (the default after calling vsa_init), the text cursor is not updated after a new text string is written with vsa_write_string or vsa_write_string_alt. If 'mode' is '1', then the text cursor is moved to the end of the text string after executing vsa_write_string or vsa_write_string_alt. Availability: In VSA256 Graphics Library Version 1.0 and up. Comments: If the text cursor mode is set to '1', the programmer may override the cursor operation as follows. If a '\r' is placed at the end of the text string, the text cursor X value will reset to the beginning of the text string (equivalent to a carriage return). If a '\n' is placed at the end of the text string, the cursor Y value advances by YCharSize pixels (equivalent to a line feed). Putting '\r\n' at the end of a text string results in a line feed and carriage return. 3.5.6 vsa_get_text_cursor_mode Prototype: unsigned vsa_get_text_cursor_mode(void); Description: This routine returns the mode of the text cursor operation. Availability: In VSA256 Graphics Library Version 4.0 and up. 3.5.7 vsa_write_string Prototype: void vsa_write_string(int x,int y,unsigned color, char far *string); Description: This routine writes a null terminated text string 'string' at position (x,y). The text is written with the 'color' passed to this routine. After execution, if the text cursor mode is '0', the text cursor remains at 'x,y', otherwise it is set to the end of the text string just written (see comments in section 3.5.5). Page: 22 Availability: In VSA256 Graphics Library Version 1.0 and up. Comments: This routine was redefined in version 3.0 to support the new vector stroked fonts. The text is drawn with vector strokes at the scale factor determined by the vsa_set_text_scale routine. Full 2D clipping is performed according to the values set with the vsa_set_clip_mode and vsa_set_viewport routines. 3.5.8 vsa_write_string_alt Prototype: void vsa_write_string_alt(char far *string); Description: This routine writes a null terminated text string 'string' at the current text cursor position as determined by vsa_set_text_cursor. The text is written with the current text color. After execution, if the text cursor mode is '0', the current text cursor remains unchanged, otherwise it is set to the end of the text string just written (see comments in section 3.5.5). Availability: In VSA256 Graphics Library Version 1.0 and up. Comments: This routine was redefined in version 3.0 to support the new vector stroked fonts. The text is drawn with vector strokes at the scale factor determined by the vsa_set_text_scale routine. Full 2D clipping is performed according to the values set with the vsa_set_clip_mode and vsa_set_viewport routines. 3.6 Basic Drawing Functions 3.6.1 vsa_move_to Prototype: void vsa_move_to(int x,int y); Description: This routine sets the current cursor position to 'x,y'. The current cursor position is used by the vsa_line_to, vsa_rect_fill, and vsa_rect functions. Availability: In VSA256 Graphics Library Version 1.0 and up. 3.6.2 vsa_set_pixel Prototype: void vsa_set_pixel(int x,int y); Description: This routine draws a single pixel at 'x,y' with the current drawing color. Availability: In VSA256 Graphics Library Version 1.0 and up. Page: 23 3.6.3 vsa_get_pixel Prototype: unsigned vsa_get_pixel(int x,int y); Description: This routine returns the current pixel value at screen coordinates 'x,y'. Availability: In VSA256 Graphics Library Version 3.0 and up. Comments: Unpredictable things may happen if you try to get a pixel that is outside of the XResolution-1 screen dimensions. 3.6.4 vsa_line_to Prototype: void vsa_line_to(int x,int y); Description: This routine draws a line from the current cursor position to 'x,y' with the current drawing color. Then the current cursor position is moved to 'x,y'. Availability: In VSA256 Graphics Library Version 1.0 and up. 3.6.5 vsa_gouraud_line Prototype: void vsa_gouraud_line(int x0,int c0,int x1,int c1,int y); Description: This routine draws a color interpolated line from the 'x0,y' to 'x1,y1'. The pixel color value is linearly varied from a starting value of 'c0' at 'x0,y' to an ending value of 'c1' at 'x1,y'. This technique of color interpolation is named Gouraud shading after the famous Joe-Bob** Not Really! Gouraud ... a French guy. Valid values for 'c0' and 'c1' are 0 through 255 and serve as indexes into the Color Look Up Table. Gouraud shaded lines serve as a fundamental drawing element for realistic 3-D graphics. The current cursor position remains unaffected by this routine. Availability: In VSA256 Graphics Library Version 2.0 and up. 3.6.6 vsa_rect Prototype: void vsa_rect(int x,int y); Description: This routine draws a rectangle from the current cursor position to the rectangles diagonal position 'x,y' with the current color. Availability: In VSA256 Graphics Library Version 1.0 and up. Page: 24 3.6.7 vsa_rect_fill Prototype: void vsa_rect_fill(int x,int y); Description: This routine draws a filled rectangle from the current cursor position to the rectangles diagonal position 'x,y' with the current color. Availability: In VSA256 Graphics Library Version 1.0 and up. 3.6.8 vsa_triangle Prototype: void vsa_triangle(int x0,int y0,int x1,int y1,int x2,int y2); Description: This routine draws a triangle defined by the 3 vertices 'x0,y0', 'x1,y1', and 'x2,y2'. The triangle is drawn with the current drawing color. The current cursor position remains unaffected by this routine. Availability: In VSA256 Graphics Library Version 4.0 and up. Comments: If Triangle clip mode is off (see vsa_set_triangle_clip_mode), triangle drawing is significantly faster (see Sec. 5.1). 3.6.9 vsa_triangle_fill Prototype: void vsa_triangle_fill(int x0,int y0,int x1,int y1,int x2,int y2); Description: This routine draws a filled triangle defined by the 3 vertices 'x0,y0', 'x1,y1', and 'x2,y2'. The triangle is drawn with the current drawing color. The current cursor position remains unaffected by this routine. Availability: In VSA256 Graphics Library Version 2.0 and up. Comments: If Triangle clip mode is off (see vsa_set_triangle_clip_mode), triangle drawing is significantly faster (see Sec. 5.1). 3.6.10 vsa_shaded_triangle Prototype: void vsa_shaded_triangle(int x0,int y0,int c0,int x1,int y1, int c1,int x2,int y2,int c2); Description: This routine draws a color interpolated triangle defined by the 3 vertices 'x0,y0', 'x1,y1', and 'x2,y2'. The pixel color value is linearly varied in 2 dimensions across the surface of the triangle using the values 'c0', 'c1', and 'c2' as the starting colors at the Page: 25 respective vertices. This technique of color interpolation is named Gouraud shading after the famous Joe-Bob** Not Really! Gouraud ... a French guy. Valid values for 'c0', 'c1', and 'c2' are 0 through 255 and serve as indexes into the Color Look Up Table. Gouraud shaded triangles serve as a fundamental drawing element for realistic 3-D graphics. (Basically, most 3-D surfaces can be constructed out of shaded triangles). The current cursor position remains unaffected by this routine. Availability: In VSA256 Graphics Library Version 2.0 and up. Comments: If Triangle clip mode is off (see vsa_set_triangle_clip_mode), triangle drawing is significantly faster (see Sec. 5.1). 3.6.11 vsa_h_line Prototype: void vsa_h_line(int y,int x0,int x1); Description: This routine draws a horizontal line from 'x0,y' to 'x1,y'. The line is drawn with the current drawing color. For horizontal lines this function is quicker than the vsa_line_to function. Availability: In VSA256 Graphics Library Version 1.0 and up. 3.6.12 vsa_v_line Prototype: void vsa_v_line(int x,int y0,int y1); Description: This routine draws a vertical line from 'x,y0' to 'x,y1'. The line is drawn with the current drawing color. For vertical lines this function is quicker than the vsa_line_to function. Availability: In VSA256 Graphics Library Version 1.0 and up. 3.7 Specialized Drawing Functions 3.7.1 vsa_raster_line Prototype: void vsa_raster_line(int x0,int x1,int y, unsigned char far *array); Description: This routine draws a horizontal raster line from 'x0,y' to 'x1,y'. The 'array[]' values specify each pixel's color value. If x0 <= x1, then 'array[0]' defines the color of the first pixel in the line at 'x0,y'. If x1 < x0, then 'array[0]' defines the color of the first pixel in the line at 'x1,y'. The vsa_raster_line routine is typically used to draw images on the display one raster line at a time. Page: 26 Availability: In VSA256 Graphics Library Version 1.0 and up. 3.7.2 vsa_get_raster_line Prototype: void vsa_get_raster_line(int x0,int x1,int y, unsigned char far *array); Description: This routine gets a horizontal raster line from 'x0,y' to 'x1,y'. The 'array[]' is loaded with each pixel's color value. If x0 <= x1, then 'array[0]' defines the color of the first pixel in the line at 'x0,y'. If x1 < x0, then 'array[0]' defines the color of the first pixel in the line at 'x1,y'. The vsa_get_raster_line routine is typically used to read back images already drawn on the display one raster line at a time. Availability: In VSA256 Graphics Library Version 2.0 and up. Comments: This routine limits x0 and x1 within the range of 0 and XResolution-1. If x0 goes negative, the first element of 'array' holds the pixel at x=0 and less than x1-x0+1 pixels will be loaded into 'array'. Likewise, if x1 is greater than XResolution-1, less than x1- x0+1 pixels will be loaded into 'array'. 3.7.3 vsa_image_size Prototype: unsigned long vsa_image_size(int x0,int y0,int x1,int y1); Description: This routine calculates the size of the image defined within a rectangle bound by 'x0,y0' and 'x1,y1'. The size of the image plus 4 is returned. The vsa_image_size routine is typically used to determine the size of the image array to be allocated and used in the vsa_get_image and vsa_put_image routines. Availability: In VSA256 Graphics Library Version 3.0 and up. 3.7.4 vsa_get_image Prototype: void vsa_get_image(int x0,int y0,int x1,int y1, unsigned char huge *image_array); Description: This routine gets the image defined in the rectangle 'x0,y0' to 'x1,y1' and stores it in the memory buffer pointed to by 'image_array'. The memory for 'image_array' must be allocated prior to this call. Upon returning from this routine, the first 2 bytes of the 'image_array' buffer contain the image width, and the second 2 bytes contain the image height. The remaining bytes in the 'image_array' buffer hold the image pixel data. Page: 27 The vsa_get_image routine is typically used in conjunction with the vsa_put_image routine for BitBLT operations. Availability: In VSA256 Graphics Library Version 3.0 and up. Comments: This routine clamps x0, y0, x1, and y1 to zero. If any of these parameters are less than zero, vsa_get_image overrides them with zero and less than (x1-x0+1)*(y1-y0+1) pixels will be loaded into 'image_array'. No limiting of y0 and y1 to YResolution-1 is performed so that off screen memory can be used as scratch pad area (see Sec. 5.3). 3.7.5 vsa_put_image Prototype: void vsa_put_image(int x0,int y0,unsigned char huge *image_array, int raster_op); Description: This routine displays the image defined in the 'image_array' buffer starting at screen coordinates 'x0,y0'. The image width and height are determined by the first two 16 bit words of the 'image_array' buffer. The 'raster_op' parameter determines how the data in the 'image_array' buffer are merged with the existing screen data, as defined below. raster_op Function 0 Replace existing data. 1 AND with existing data. 2 OR with existing data. 3 XOR with existing data. 4 Reserved .... Do Not Use !! 5 Reserved .... Do Not Use !! 6 Replace existing data only with non-zero pixels (Sprites!). The vsa_put_image routine is typically used in conjunction with the vsa_get_image routine for BitBLT operations. Availability: In VSA256 Graphics Library Version 3.0 and up. Page: 28 4.0 NITTY GRITTIES 4.1 Registration Information If you find the VSA256 Graphics Library useful, a registration of $34 would be appreciated. Registration brings with it MAJOR BENEFITS, as spelled out in section 1.2, so look at the ORDER.TXT file and fill it out! Please fill out the Information About You and the Wish List sections, and indicate the version number of the software you are presently using. Send check or money order to: Spyro Gumas 7910 W. Brookridge Drive Middletown, MD 21769 ****** COMPUSERVE - SWREG ID: 5417 ****** If you are on CompuServe, you can register through SWREG. Just "GO SWREG", then give them the registration ID: 5417. They will bill you $49.00 and I'll send you both VSA256 and TIFF256 graphics Libraries (plus the goodies!). Please do fill out and send me the information form so you can tell me what you want in the next revision. Page: 29 4.2 Software License VSA256 Graphics Library, Version 4.0 Copyright Spyro Gumas, 1992 - 1996. All Rights Reserved. The VSA256 Graphics Library is a "shareware program" and is provided at no charge to the user for evaluation. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using The VSA256 Graphics Library and continue to use The VSA256 Graphics Library after a reasonable trial period, you must make a registration payment of $34 to Spyro Gumas. The $34 registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. You are free (and encouraged) to copy and distribute the VSA256 Graphics Library if: 1) It is not used as a component of another software library. 2) No fee is charged for use, copying or distribution. 3) It is distributed as is (preferably as VSA256.ZIP) and not modified in any way. Furthermore, you are granted royalty free use of The VSA256 Graphics Library executable code in any of your programs given that: 1) You have registered your use of The VSA256 Graphics Library and paid the $34 registration fee. 2) It is not used as a component of another software library. 3) You visibly acknowledge the use of The VSA256 Graphics Library in your product in both the printed materials and the executable software with the following statement: "This software uses the VSA256 Graphics Library, Copyright Spyro Gumas, 1992 - 1996. All Rights Reserved" Clubs and user groups may charge a nominal fee (not to exceed $10) for expenses and handling while distributing the VSA256 Graphics Library. Anyone distributing The VSA256 Graphics Library for any kind of remuneration must first contact Spyro Gumas at the address below for authorization. This authorization will be automatically granted to distributors recognized by the (ASP) as adhering to its guidelines for shareware distributors, and such Page: 30 distributors may begin offering The VSA256 Graphics Library immediately (However Spyro Gumas must still be advised so that the distributor can be kept up-to-date with the latest version of The VSA256 Graphics Library.). Commercial users of The VSA256 Graphics Library must register and pay for their copies of The VSA256 Graphics Library within 30 days of first use or their license is withdrawn. Consult the file ORDER.TXT for more information or contact Spyro Gumas. 4.3 Disclaimer Users of The VSA256 Graphics Library must accept this disclaimer of warranty: The VSA256 Graphics Library is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of The VSA256 Graphics Library. In no event shall the author's liability for any damages ever exceed the price paid for the license to use The VSA256 Graphics Library, regardless of the form of the claim. The person using The VSA256 Graphics Library bears all risk as to the quality and performance of this software. 4.4 Technical Support If you have any questions or comments about the VSA256 Graphics Library, please write me at: Spyro Gumas 7910 W. Brookridge Drive Middletown, MD 21769 Or, contact me on EMAIL! CompuServe: 71064,1571 Internet: 71064.1571@compuserve.com And Make Sure to visit my WEB PAGE at: http://ourworld.compuserve.com/homepages/blueberry Page: 31 5.0 APPLICATION NOTES 5.1 Using Triangles Starting with VSA256 V4.0, the programmer can turn off clipping specifically for triangle drawing operations via the vsa_set_triangle_clip_mode routine. You may ask "why is this a reasonable thing?". One of the intended uses for the vsa_shaded_triangle routine is to use lots of small shaded triangles to form large 3D shaped surfaces. The process of breaking down the large surface into small patches is called "tessellation" (I think). If you actually go to the effort of writing software to do this, maybe using Bezier curves or B-splines, you could also clip the large surface dimensions to the clipping window prior to the tessellation process. If you do so, and turn off triangle clipping, you will eliminate the overhead of having to clip test the hundreds of tiny triangles that are mostly within the window anyway. Turning triangle clipping off doubles the drawing speed of 30 x 30 x 42 pixel triangles using vsa_shaded_triangle. 5.2 Page Flipping Ever since VSA256 V1.0, the vsa_set_display_start routine has been available for page flipping (Ping-Pong Buffering) of the video memory. But I'll be the first to admit that using this feature was not intuitive. You had to turn off all clipping and then draw in off screen Y coordinates to get to the second page... what a mess. VSA256 V4.0 cleans up all of this confusion. With vsa_set_draw_page and vsa_set_view_page, the programmer no longer has to think about the details. After vsa_init, DRAW_PAGE and VIEW_PAGE both = 0. The programmer can follow the following sequence for professional looking results. - vsa_set_draw_page(1); // flip to video page 1 for drawing. - vsa_set_color(0); // set to background color. - vsa_move_to(0,0); - vsa_rect_fill(XResolution-1,YResolution-1); // Clear page 1. - BlahBlahBlah // Do all of your drawing. - vsa_wait_vsync(); // optional. - vsa_set_view_page(1); // Display page 1 on screen. - vsa_set_draw_page(0); // flip to video page 0 for drawing. - repeat clearing and drawing into vid page 0 now. 5.3 Using Off Screen Video Memory You may find it convenient to create small bit maps (Sprites?) and store them off screen in undisplayed video memory, for instance all of the cute little buttons used in a GUI program. Then you can use vsa_get_image to snatch them up and vsa_put_image to plop them down somewhere on the displayable screen. This would be of particular interest to a programmer who is fresh out of extra memory to allocate for the storage of these bitmaps. Page: 32 To do this, all you need is to set the viewport 'bottom' value far enough below the bottom of the displayable video memory to leave room for your bitmaps. For example, say you are running in 800x600 video mode and you have 25 bit mapped buttons of 32x32 size each which you would like to predraw and store. Set the clipping viewport to include pixel row 631 with vsa_set_viewport(0,0,799,631). Now go ahead and draw your buttons in the space between 0,600 and 799,631. The display will only show the area between 0,0 and 799,599 ... your buttons won't show. But they are there and you can access them with vsa_get_image and you can display them with vsa_put_image. Pretty cool huh? 5.4 Expanding the VSA_FONT Character Set Starting with VSA256 V4.0 you can change the number of possible characters in the font array. If you want to increase the total number of characters, just change the '96' dimension in the 'ASC[96][72]' declaration in the VSA_FONT.H file to the new desired number of characters. Then make sure to fill out the remainder of the array. This new capability is a result of strong international pressures. Now you folks can go and customize your own, large, international font sets. How about if you share these new VSA_FONT.H files with me and I can make them available to all users via my Web page? 6.0 GRAPHICS LIBRARY EXTENSIONS The VSA256 Graphics Library is a base library which is supported by Graphics Library Extensions (GLEs) for more specialized tasks. These GLEs are typically shareware and new ones are developed periodically. 6.1 THE VSA256 GLE DEVELOPERS PROGRAM I want to encourage people to write VSA256 GLEs. The reason is simple. As the number of available GLEs grows, so does the applicability of the VSA256 Graphics Library to various software applications. As this happens, the demand for the VSA256 Graphics Library grows, and the better off I become. For this reason, I started the VSA256 GLE Developers Program (VGDP). What Is It? The VGDP is an incentive arrangement between myself and GLE developers by which I get developers to write VSA256 GLEs. How's It Work? A developer writes a VSA256 GLE and sends it to me. If it adds a unique capability and it meets my quality standards, it is added to the list of goodies that I offer to registered users. When a user registers for the VSA256 Graphics Library, in addition to the normal stuff, I also send him the VSA256 GLE. If he likes your GLE, he can register for it by sending you payment. Page: 33 What's In It For Me? Clearly I get a lot of benefits. 1) The overall demand for the VSA256 Graphics Library goes up. 2) I get to use your GLE as an incentive for people to register for my software. 3) I don't have to write all of the VSA256 related GLEs out there. 4) I get to meet a lot of interesting people doing really interesting things. What's In It For You? You wouldn't do this unless you also benefit, right? 1) Exposure of your product. The VSA256 Graphics Library has been around since 1991 and has developed quite a following. - The VSA256 Graphics Library has been featured in two books by SAMs Publishing (Tricks of the Graphics Gurus and PC Graphics Unleashed). - New GLEs will receive exposure in any subsequent book deals. - Your GLE gets exposure through the flyers I send out. - I feature each of the existing VSA256 GLEs on my home page. 2) Ready made market. The VGDP lets you take advantage of an existing base of people already programming with the VSA256 Graphics Library. If you have a useful GLE, they will be anxious to get there hands on it. 3) The VGDP is a helping hand in getting your shareware business up and running. You can start from scratch, but it sure is easier to ride on the coat tails of a successful product. A suggestion - A submission to the VGDP should be a self contained, preferably zipped package which is ready to go to the user and includes as a minimum: - The Library File - Any Include Files - Demo Program - Documentation File - Order Form (So they can send you registration payments) Some possible VSA256 GLEs: - A GUI - A really robust 3D library - Integrating Sound into the VSA256 environment - How about a 3d fly by phase shifting Doppler corrected sound modeler - Fancy 3D stuff - Fancy Text Manipulation Stuff - Various Image readers. Page: 34 6.2 EXISTING GRAPHICS LIBRARY EXTENSIONS TIFF256 Graphics Library Extension 4.0 - This library extension provides functions which operate with Tagged Image File Format (TIFF) images. With these functions, you can traverse the image file, extract image information, and display the images as part of your own program. You can also modify the TIFF images and write them back to TIFF files. Furthermore, any image that you generate with VSA256 can be saved as a TIFF file. The image types supported include Bilevel, Grayscale, Palette Color and RGB True Color. Adaptive Color Palette generation is supported for 24 bit images. This makes most True Color images show up undistorted by the 256 color limitation. Compressed TIFF files are also supported for reading and writing. The full function version of the TIFF256 Graphics Library Extensions is shareware, available from the same place that you got the VSA256 Graphics Library. CBTMouse API Library 1.0 - New from CyberBase Technologies, Inc., this library adds complete mouse interaction to your graphics applications. These guys go all out to make mouse driven graphics programming a breeze. Functions provided include initialization, displaying and hiding mouse, reading position, setting position, reading button status, working within bounding boxes, changing cursor color and size, and waiting for various mouse inputs. You get a very functional version of this library when you register for the VSA256 Graphics Library. The full up library (version 1.0) is shipped by CyberBase Technologies, Inc. upon a nominal registration fee. VSA3D Library 1.0 - This library lets you write 3D applications. What ever your interests, Mechanical Design, Architecture, Interior Design, Space Widgets, you name it, you can do it. Functions provided let you add and delete objects from a display list, set the view point, and perform 3D transformations including scale, offset, and rotation. Select the drawing mode for the 3D objects from Wireframe, Solid, or Gouraud (smooth) Shaded. You get a very functional version of this library when you register for the VSA256 Graphics Library. Page: 35 7.0 APPENDIX 7.1 VSA.H Include File /*.................................. VSA.H ................. 2-24-96 .......*/ /* This file declares the VSA256 Graphics Library functions and global */ /* parameters used throughout the graphics routines. */ /* */ /* VERSION 4.0 */ /* */ /* Copyright Spyro Gumas, 1992 - 1996. All Rights Reserved. */ /*..........................................................................*/ /*..........................................................................*/ /* External Function Prototypes */ /*..........................................................................*/ extern unsigned far vsa_set_svga_mode( unsigned ); extern unsigned far vsa_get_svga_mode( unsigned far * ); extern unsigned far vsa_set_display_start( unsigned, unsigned ); extern unsigned far vsa_get_display_start( unsigned far *,unsigned far * ); extern unsigned far vsa_init( unsigned ); extern void far vsa_set_color( unsigned ); extern unsigned far vsa_get_color(void); extern void far vsa_set_text_color( unsigned ); extern unsigned far vsa_get_text_color(void); extern void far vsa_set_text_cursor_mode( unsigned ); extern unsigned far vsa_get_text_cursor_mode(void); extern void far vsa_set_text_cursor( int, int); extern void far vsa_get_text_cursor( int far *, int far *); extern void far vsa_set_text_scale(float,float); extern void far vsa_get_text_scale(float far *,float far *); extern void far vsa_set_viewport( int, int, int, int); extern void far vsa_get_viewport(int far *,int far *,int far *,int far*); extern void far vsa_set_clip_mode( unsigned ); extern unsigned far vsa_get_clip_mode(void); extern void far vsa_set_triangle_clip_mode(int mode); extern int far vsa_get_triangle_clip_mode(void); extern void far vsa_write_string( int, int, int, char far * ); extern void far vsa_write_string_alt( char far * ); extern void far vsa_read_color_register( unsigned, unsigned char far *, unsigned char far *,unsigned char far *); extern void far vsa_write_color_register( unsigned, unsigned char, unsigned char,unsigned char ); extern void far vsa_read_color_block(unsigned, unsigned,unsigned char far * ); extern void far vsa_write_color_block(unsigned, unsigned,unsigned char far *); extern void far vsa_move_to( int, int); extern void far vsa_set_pixel( int, int); extern unsigned far vsa_get_pixel( int, int); extern void far vsa_line_to( int, int); extern void far vsa_triangle( int, int, int, int, int, int); extern void far vsa_triangle_fill( int, int, int, int, int, int); extern void far vsa_rect_fill( int, int); Page: 36 extern void far vsa_rect( int, int); extern unsigned long far vsa_image_size( int, int, int, int); extern void far vsa_get_image( int, int, int, int,unsigned char huge * ); extern void far vsa_put_image( int, int,unsigned char huge *, unsigned); extern void far vsa_h_line( int, int, int); extern void far vsa_v_line( int, int, int); extern void far vsa_raster_line( int, int, int, unsigned char far *); extern void far vsa_get_raster_line( int, int, int,unsigned char far *); extern void far vsa_gouraud_line( int, int, int, int, int); extern void far vsa_shaded_triangle(int,int,int,int,int,int,int,int,int); extern void far vsa_wait_hsync( void ); extern void far vsa_wait_vsync( void ); extern void far vsa_about( void ); extern void vsa_set_draw_page(int); extern int vsa_get_draw_page(void); extern void vsa_set_view_page(int); extern int vsa_get_view_page(void); /*..........................................................................*/ /* External Parameter Declarations */ /*..........................................................................*/ extern unsigned far XResolution, far YResolution; extern unsigned far XCharResolution, far YCharResolution; extern unsigned char far XCharSize, far YCharSize; extern unsigned char far BitsPerPixel; extern int far XLeft, far XRight, far YTop, far YBottom; extern float far Text_X_Scale, far Text_Y_Scale; extern int far VSA_ATI_COLOR; Page: 37 7.2 VSA_FONT.H Include File /*............................... VSA_FONT.H .............. 2-17-96 ........*/ /* This is the font file for the VSA256 Graphics Library. The basic */ /* font size is set by the XCharBase and YCharBase values defined at the */ /* top of this file. This include file gives you the ability to fully */ /* customize your fonts! Feel free to edit the font vertex lists to be as */ /* personalized as possible. Read on to see how it works. */ /* */ /* ASC[M][N] is a 2 dimensional array. The M index selects one of 96 */ /* possible characters and corresponds to the printable ASCII character */ /* codes from 32 to 127. (M = 0 selects ASCII character code 32 ... a space,*/ /* M = 95 selects ASCII character code 127 ... DEL) */ /* For any given value of M, the N index steps through the vertex list */ /* for that character. Each vertex takes up 3 locations. The first of */ /* the 3 values is the blank code. A blank code of 0 means start a new line */ /* segment (equivalent to "move_to"). A blank code of 1 means continue */ /* drawing (equivalent to "line_to"). A blank code of 255 means END of */ /* vertex list. You MUST end each vertex list this way! */ /* The next two values are x and y coordinates relative to the top left */ /* corner of the character cell. The x and y values should never be more */ /* than XCharBase-1 and YCharBase-1 respectively. When the blank code is */ /* 255, the x and y values are ignored. A maximum of 23 verticies plus an */ /* END vertex are allowed per character. Overrunning this limit will */ /* probably cause your PC to go woopie. */ /* */ /* Starting with version 4.0 of this library, the user can change the */ /* number of possible characters in the font array. If you want to */ /* increase the total number of characters, just change the '96' dimension */ /* below in the 'ASC[96][72]' declaration to the new desired number of */ /* characters. Then make sure to fill out the remainder of the array. */ /* */ /* VERSION 4.0 */ /* */ /* Copyright Spyro Gumas, 1992 - 1996. All Rights Reserved. */ /*..........................................................................*/ /*..... 12-14-94 Added 'far' to declarations. .....*/ /*..... 2-17-96 Now user can change '96' dimension of ASC array. .....*/ unsigned far XCharBase = 8, far YCharBase = 16; unsigned char far ASC[96][72]={... Array initialization not printed here ... ... for brevity. See VSA_FONT.H file for ... ... details. ... Page: 38